The Atari Compendium/The Atari Compendium (Toad Computers) (1994).iso/files/prgtools/editors/vix.arc/VIX.DOC

Text File | 1986-03-08 | 28.3 KB | 610 lines

                         VIX Reference Manual



     This is the Reference Manual for VIX, a full screen editor
written in C by Dr. Bruce E. Wampler.  (Current address: Dr. Bruce E.
Wampler, University of New Mexico, Department of Computer Science,
Farris Engineering Center, Albuquerque, NM 87131; uucp: ...{ucbvax |
gatech | ihnp4!lanl}!unmvax!wampler).  Any comments, bug reports, or
suggestions should be sent to that address.  Full source code
is also avaiable.

     VIX is NOT Vi, but a close emulation based on the editor called
TVX. While the majority of the common commands are identical, there
are some inherent differences in the way TVX and Vi treat text.
Whenever possible, VIX emulates Vi commands exactly.  When that wasn't
possible, the emulation won't produce a surprise, or will be implemented
as a completely different command name.  (Mostly as 'q' prefix commands.)
None of the underlying ex commands are avaiable.

     This version of VIX Copyright (c) 1986 by Bruce E. Wampler.
Permission is hereby granted for free, unrestricted nonprofit use of
this software.  Please feel free to modify, distribute, and share this
software as long as you aren't making any money from it.  If you want
to use this code in a profit making environment, please contact the
author for permission.



********* General Notes

    Most commands also take an optional numeric count.  The default
count is always one.  Commands that allow a count value are preceded
by the letter 'n' in the following descriptions.  Whenever a command
produces output or an error message, it appears on the bottom line
of the screen.

     The BACKSPACE key (Control-H on some terminals) is used to edit
input text.  When VIX is accepting commands, BACKSPACE will cause the
character immediately before the cursor to be deleted.

     Vi uses the ':' command to read and write the file (among other
things).  Vix uses the ':' to set operating parameters such as
autoindent, screen size, etc.  The 'ZZ' (or 'ZA' to abort without
changes) command is used by vix to exit.

     Vix does not have the underlying ex editor, so none of the escape
to ex commands work.  Vix does have the TVX repeat loop, however, and
this compensates to a great extent for the need for ex features.
Please consult the TVX manual for examples of using the repeat loop.
Note that when using the repeat loop with vix, the commands will be
vix commands and not tvx commands.

     VIX uses two techniques for protecting the original file from
editing mistakes.  First, each time a file is edited, a new version is
created, and the previous version retained in its original form as a
backup.  This file will change the original file extension to '.BAK'.



*****  The Text Buffer and Moving Text

     The VIX emulation works entirely in the available memory for
editing.  The text from the file which is being edited is held in a
buffer in main memory.  If a file is particularly large, it may not
entirely fit into main memory. The buffer size limit in no way restricts
the total size of a file that can be edited by VIX.  To make editing
large files easier, some commands apply to the entire file and cause
automatic cross buffer manipulation.

     VIX actually divides the internal memory into two parts: the text
buffer and the save buffer.  The text buffer (or simply the buffer) is
used to hold the file (or part of the file) being edited.  There is
only one such text buffer. The save buffer is used for moving text,
both from one part of the text buffer to the other, as well as to
and from external files.  The maximum size of the save buffer depends
on the amount of text currently residing in the main text buffer.
The following diagram shows the internal VIX memory organization:

   +-----------------------------+
   |  TEXT BUFFER - the current  |
   |  text (or portion) of file  |
   |  being edited. (grows down) |
   |            _________________|
   |___________|                 |
   |  free memory        ________|
   |_____________________|       |
   |  SAVE BUFFER - grows up     |
   +-----------------------------+

     Text is added to the text buffer when the file is first read in
(or created).  If the file doesn't fit into one buffer, you will have
to manually "page" the text into the buffer.  Text is added to the
save buffer in one of several ways.  VIX has added commands to move
text from the text buffer to the save buffer, and move the
contents of the save buffer to the text buffer.  VIX also has "cut
mode".  When cut mode is enabled (the default), when lines are killed,
they are automatically copied into the save buffer as well as being
deleted from the text buffer.  When off, deleted lines are not saved.
It is also possible to save the contents of the save buffer to a
new external file, and to load the save buffer from an external file.

     'P' and 'p' are used with 'y' and '^Y' to move text around.  'P'
causes the text in the save buffer to be inserted before the current
cursor position.  'p' is used to insert the save buffer after the
current line. The saved text remains in the save buffer.

     The 'y' command command will yank (save) the current line in
the save buffer, and move the cursor down one line.  On the screen,
'y' appears to have the same behavior as 'j'.  If n is supplied,
then n lines will be yanked.  'y' can also be used sequentially.
If no other commands intervene, consecutive 'y' commands will continue
adding lines to the save buffer.  If any other commands are entered
between consecutive 'y' commands, the previous contents of the save
buffer will be lost, and replaced with the new line.  If cut mode
is on (the deault), a 'dd' will overwrite the save buffer! The 'Y'
command can be used to append lines to the current save buffer without
losing the previous contents.

     The 'd/' command can be used with 'y' 'Y', 'P' and 'p' to move
text.  Use 'y' to save the text to be moved, immediately delete the
saved text with 'd/', then insert it at the new place with 'p' or 'P'.
The last line of the file is can be saved in the save buffer only
once, and an error message will be printed if you attempt to save
the last line a second time.

     A 'qy' is similar to 'y' yank, but the text saved in the save
buffer is read in from an external file instead of from the text
buffer.  When 'qy' is entered, the save buffer is cleared, and the
user is prompted for the name of the file to read.  VIX then will
read as much of the external file into the save buffer as it can.
The 'P' or 'p' command can then be used to insert the save buffer
text into the current file at the desired location.  If there is
not enough room in the save buffer to hold the entire file, then
only part of the file is read and a diagnostic message printed.

A 'qp' causes the contents of the save buffer will be written to
a new file.  After 'qp' is entered, you will be prompted for the
name of the output file, and then the contents of the save buffer
will be written to that file.

     The 'qw' command is used to explicitly go from one
buffer to the next.  By default, when n is >= 0, the entire current
buffer is written to the new version of the file being edited, and the
next buffer full of the original file (if any) is read in.  If a
negative n is supplied (any negative value, most easily '-qw'), then
only the part of the buffer up to (but not including) the current
line is written.  Then as much more of the file as possible is read
to the end of the current buffer.  Thus, a negative n is useful when
a file won't fit, and the split point is at an awkward place.  It
is also useful when a 'qy' yanked file won't fit.


*****  Searching

     Unlike Vi, end of lines are not special to VIX.  Thus all the
cursor movement commands and delete single character commands will
treat the end of line as just another character.  This also means
that a <Return> (end of line) is a valid search character, and thus
makes it impossible to end a find pattern with a <Return>.  The <Escape>
key is used to mark the end of a find pattern.  VIX also supports
find pattern wild cards somewhat different that standard VI.

     Another basic concept of VIX is the "last thing." Whenever VIX
finds a pattern from the search command, skips over a word, or gets
from or puts to the save buffer, that text is considered the "last
thing."   The 'd/' will delete the "last thing".
While this is this a powerful editing concept, it does have some
consequences.  First, the cursor will always be placed AFTER the
pattern just found.

     The search normally ignores the case of the letters in the pattern.
If the 'q:f' parameter is set with 0 ('0q:f'), then search command
will match only the exact case.  If the pattern is found, then the
cursor will be placed immediately following the pattern.  The pattern
may be at most 100 characters long.

     VIX supports extensive wild card matching.  The 'q:m' set
parameter controls whether or not wild card matching is turned on.
Normally, it is.  The wild card matching in VIX is based on the
concept of 'sets of special characters'.  VIX predefines 6 sets of
characters, and allows the user to define one additional set.  When a
special control character is included as part of the find pattern,
then any character in the specified set will match the pattern.  The
predefined sets are:

    ^A - Alphanumeric characters: a-z, 0-9
    ^D - Digits: 0-9
    ^L - Letters: a-z
    ^O - Other characters: all characters except a-z, 0-9
    ^P - Punctuation: '.', ',', '!', '?'
    ^X - Any character: any printable character
    ^U - User character: any character in user set, set by ':U'

     Any of the sets may be specified by entering the proper control
character in the find pattern: Control-A for the ^A set.  Thus,
entering a find pattern of '^L^D' would match any letter followed by
any digit.  Since it may be desirable to match a sequence of one of
the character sets, two prefix characters are supported.  A '^W'
before one of the above sets will match a 'word' of that set.  Thus,
'^W^L' will match any word, and '^N^D' will match any number.  The
find pattern 'st^W^L' would match words starting with 'st'.  The '^N'
prefix is used to make a 'word' of characters NOT included in the
given set.  Thus, '^N^L' will match a 'word' of characters NOT
including the letters a-z.  A match 'word' consists of any sequence of
characters (at least one character long) found in the given set, up to
the first character not in the set.  End of lines also terminate all
wild card patterns.  The only real way to adequately understand VIX
wild cards is to use them in practice.

     The last pattern found with the find command (up to 100 characters)
is saved in an internal buffer.  The '*' command will insert that
pattern into the text at the current cursor location.  If the last
find pattern included wild card characters, the pattern saved will
be the actual text matched, and not the wild cards themselves.

     'q/' is the same as '/', except the search will cross buffer
boundaries.  Whenever a buffer is searched without finding the pattern,
the next buffer will be read in.  The screen will not change until
the pattern is found or the file is exhausted.  If the pattern is
not found anywhere, then the entire file will have been written out,
and there will be an empty buffer.  The 'qb' command may be used
at that point to get back to the beginning of the file.




***** Repeat loops

     Probably the most powerful editing tool provided by VIX is the
repeat loop.  This allows arbitrary command sequences to be entered,
and repeated any number of times.  VIX will have at least 5 different
repeat buffers.  The repeat loop is used instead of the standard Vi
macro command facility.

     When 'n<' is entered, the editor echoes 'Repeat: n<' at the
bottom of the screen. The user then types in any series of commands
to be repeated n times. The repeat command is terminated with a
matching '>' and a double escape (echoed as $$).  Repeat loops may
not be nested.  The repeat loop has two typical useful functions:
one is to replace multiple occurrences of a string with another
(e.g., "10</one$c/two$>$$"), a second is to save a complicated sequence
of commands to be repeated as necessary with the '@' command (i.e.,
a macro facility).  Each repeat loop may have up to 100 characters.

     When a repeat loop is entered from the keyboard, it is saved in
one of 5 repeat loop buffers, each identified by an integer value.
The repeat buffer which is currently in use can be set with the 'nq:r'
command.  Buffer 1 will be used by default.

     The '#' command has been provided to simplify the use of the
multiple repeat buffers. Entering '23#4' for example, will cause
repeat buffer 4 to be executed 23 times

     When making repeat loops, it is easy to make a mistake.  The 'qe'
command allows any of the repeat buffers to be edited, and then the 'qr'
command can save the corrected repeat buffer back.  If you don't give
a value for n, the currently selected buffer is used.

     The 'qe' command will insert the contents of the selected repeat
buffer into the current text buffer
above the current text line.  The repeat buffer will start
with a sequence of '#n:<', where n will be replaced by the repeat
buffer being edited.  The '#n:' identifies which buffer you are
editing, and is used by the 'qr' store repeat buffer command to identify
the buffer to save to.  Escapes will be represented by '^[' instead of
the '$' used when entering a repeat buffer initially.  A '>^[^['
identifies the end of the repeat loop.

     After you have edited the repeat buffer, it can be saved with the
'qr' command.  You must place the cursor anywhere on the first line of
the repeat buffer before using 'qr'.  When you press 'qr', the buffer
will be saved in the buffer indicated right after the '#'.  Thus,
unlike 'qe', the 'qr' command accepts no n value.





***** Settable parameters

     Many of the basic operating characteristics of VIX are
controllable by user settable parameters.  These parameters are
relevant to all versions of VIX, with the current status of each
displayed on the help screen ('=' command).  These paramaters are
set using 'nq:p', where p is one of the following parameters.

nq:a - set autoindent.  A value of 1 turns on autoindent, 0 off.
   When autoindent is on, each new line started while in insert mode
   will be indented to the same leading tab/blank space as the previous
   line.  Use blanks or tabs to add indentation, and backspace to backup
   over indentation.

nq:c - set cut mode.  When cut mode is enabled (1), killed lines are
   also saved in the save buffer.  This works for individual kill
   commands, e.g.  'dd', 'dd', 'dd' will save only the line associated
   with the 3rd 'dd', while '3dd' will save 3 lines in the save buffer.
   With cut mode off, lines are not saved in the save buffer.

nq:d - set home "display" line to n. The display line is the line the
   cursor homes to after a '^L' verify command.

nq:e - Expand tab value.  The default value for ':E' is 8, which causes
   the tab character (^I) to be expanded to multiples of 8 columns.
   Setting ':E' to 0 will cause tabs to be displayed as '^I' instead.
   Other values are possible, but less useful.

nq:f - Find case mode: n <= 0 sets find mode to search for exact case
   of pattern, n > 0 (default) set search mode to ignore upper/lower
   case.

nq:m - Match wild cards.  (default=1).  If on, then matching of the VIX
   wild card sets is enabled.  If off, then the wild card control
   characters will match the actual control characters in the file.

 q:o - set output file name.  When ':o' is entered, you will be prompted
   for the name of the edited output file.  This overrides the '-o'
   command line switch, and can be used to change your mind about the
   name of the edited file.  If the output file name is different than
   the input file name, the input file will not be renamed to the
   backup file name.

nq:r - select repeat buffer n. (default=1).  Repeat buffer n becomes
   the current repeat buffer executed with the '@' command.  The '='
   will display the current contents of repeat buffers.

nq:s - scroll lines: This parameter sets how many lines the cursor will
   move before the screen scrolls.  'q:S' sets how many lines cursor
   will move above and below home display line before scrolling.

nq:t - tty mode.  A 0 is screen mode, a 1 is tty mode.  (This
   command is useless on the Atari, but useful on slow mainframes.)

q:u - set User Wild Cards.  After entering :U, you will be prompted for
   a user wild card set.  You can use backspace to correct your entry,
   and '<Esc><Backspace>' to enter backspace and '<Esc><Esc>' to enter
   escape.

nq:v - virtual window lines.  The 'n:V' will set the virtual window to
   n lines.  N must be between 3 and the number of hardware lines on
   the terminal.  This feature was desinged for busy time sharing
   systems and slow modems.

n:W - set auto wrap width.  The ':W' parameter sets the column number
   used for auto wrap mode.  When the auto wrap is set to a value
   greater that 1, VIX will automatically insert an end of line when
   the user types the first blank after the given column.




***** Word Processing Features

     VIX has some limited word processing capability.  This is the
autowrap feature, settable both when you first run VIX, and by the ':w'
parameter.  Setting autowrap to column 65, for example, will tell VIX
to automatically insert a newline whenever you enter text past that
column.

     The '!' tidy command is specifically designed to improve the
appearance of strictly text files.   The '!' tidy command will fill
source text using the same right margin currently set for auto-wrap.
Tidy performs essentially the same operation as a word processor
fill function.  Word are combined on one line until the auto-wrap
margin is passed.  The 'n' count refers to the total number of resulting
lines, not the number of original lines.  Specifying a large 'n'
will tidy large sections of a document.  The tidy command recognizes
lines beginning with blanks, tabs, or a period, and blank lines as
special.  It will not fill those lines, thus preserving paragraphs,
tables and NROFF-like dot commands.


***** Other Features

     For programmers, VIX has an autoindent command.  The ':a' parameter
controls this feature.  When enabled, VIX will automatically match the
leading white space at the beginning of the previous line.

     The 'q(' command is used to toggle between line resolutions on the
Atari ST monochrome monitor.  Each 'q(' toggles between 25, 40 and 50
line resolution.


     The 'qj' command will cause a "jump" back to the line of the
previous cursor position.  The major intent of 'qj' is to restore
the cursor position if a large cursor movement command is accidentally
entered (like when you thought you were in insert mode).  It is also
useful after using 'qb' to make a backup copy of the file.  The
sequence 'qb', 'qj' will write the file, then restore the cursor
positon.

     The 'nm' mark command notes the current line positon.  Values
of 1 to 9 are allowed for n. 'nM' restores the position. After entering '3m'
for example, you can then move around the buffer, and later use '3M'
to return to the marked location.


***** Startup and option switches


     To edit a file using VIX, enter the following command line
(if you have a shell - otherwise provide the parameters to
the TTP box):

          vix filename -switch1 -switch2 ...

     VIX has several switches which control certain operating
characteristics.  Each switch begins with a minus (-), and is
separated from the file name and other switches by a blank in the
standard UNIX/C convention.  Some switches may be negated by using a
'nox' form.  Thus, '-b' will cause a .bak file to be generated, while
a '-nob' causes the .bak file to be deleted on exit from the editor.
This capability is indicated by []'s.  As many switches as necessary
or desired can be used at one time in any order.  A ':' may be used
instead of a '=' for '-c' and '-o'.  The various switches supported
include:

     -[no]b -- generate a .B[AK] version of the original (the usual
          default).  The -nob option means no .BAK file is generated.
          This latter mode of operation follows the normal Unix
          convention of not keeping past generations of a file.
     -[no]i -- auto indent mode enabled.
     -o=filename -- send edited output to filename.  The output file
          can also be changed at any time during the editing session
          with the ':o' command.
     -r -- read only - file can be read in only
     -s -- big save buffer - leaves more buffer for save file
     -w -- word processing mode - sets autowrap on, margin to 65.
     -# -- entering a number from 3 up to the number of lines on the
          screen will create a smaller VIX editing window.  This is
          most useful for slower baud rates.  A -7 makes a nice, small
          window showing 7 lines.



************************ COMMAND SUMMARY ***************************

     The available VIX commands are summarized below.  The first
column of each entry has a character noting similarities and
differences with the real vi commands in the following fashion:

- means present in vi, not implemented in vix.
= means commands work identically {with possible minor variations}
+ means new or significantly different command
* means "equivalent" command, somewhat different than vi
<space> means command unused in both vi and vix.

  n in front of command means command takes count argument
  [synonyms indicated in brackets]

   ^@: Unused
   ^A: Unused
= n^B: Backward window. {2 lines of continuity not preserved}
   ^C: Unused
= n^D: Down half window.
-  ^E: Not implemented
= n^F: Forward window.
*  ^G: memory status, short info line
= n^H: backspace Command mode: left; Insert mode: del last char
=  ^I: inserts tab in insert mode, not a command.
= n^J: down arrow in column [j,^N]
+ n^K: up in column [k,^P]
=  ^L: verify screen [^R,z]
= n^M: down to beginning of line [+]
= n^N: [j, ^J]
   ^O: Unused
= n^P: [k, ^K]
=  ^Q: Unused (flow control)
=  ^R: Redraw screen [^L,z]
=  ^S: Unused (flow control)
+  ^T: TVX prefix command - see q [q,Q,T]
* n^U: Up half window.  ** in insert mode, does NOT erase line **
*  ^V: Not a command.  NOT literal quote in insert mode.
*  ^W: Not a command.  NOT used for delete word in insert.
   ^X: Unused
-  ^Y: Not implemented
-  ^Z: Not implemented
=  Escape: forces command mode, safe follow char for d,c,q.
   ^: Unused
-  ^]: Not implemented
-  ^^: Not implemented
   ^_: Unused
=  <space>:  [r]
+  n!: Tidy.  Fills n lines up to wrap margin. [see autowrap]
-   ": Not implemented
+ n#p: execute repeat loop number 'p' 'n' times
=   $: goto end of current line {end is newline, not last char}
-   %: Not implemented
-   &: Not implemented
-   ': Not implemented
-   (: Not implemented
-   ): Not implemented
+   *: insert last matched pattern into text buffer
=  n+: [CR, ^M]
-   ,: Not implemented
*   -: Used in vix for negative counts, use K for up line.
-   .: Not implemented, repeat loops are a substitute
=   /: search {Escape used to end pattern, multi-line patterns ok}
*   0: 0 is used for counts (especially for : parameters)
= 0-9: count value for numeric arguments {may be negative!}
-   :: Not implemented - use ZZ and ZA to exit
-   ;: Not implemented
+  n<: Begin repeat loop. Loop terminated with >$$. ($ = Esc)
+   =: Help screens
+   >: Used to terminate repeat loops.
=   ?: Reverse search {search begins on previous line}
+  n@: execute current repeat loop n times (shorthand for n#p)
=   A: append to end of line
*  nB: back a word {vix's concept of words is different than vi}
=   C: changes rest of line
=   D: delete rest of the line
-   E: Not implemented
-   F: Not implemented
=  nG: goes to line number n, or end of buffer if no n supplied
*   H: Beginning of buffer (first line in buffer)
=   I: inserts at beginning of line
=   J: join lines {not needed since vix treats newlines as chars}
+  nK: Up a line to beginning of line
*   L: bottom line of file
+  nM: return to marked location n (n from 1 to 9, see m)
=   N: like n, but in reverse direction
=  nO: open a line above current line. n opens n blank lines.
=   P: put save buffer above current line {save buffers not named}
+   T: tvx commands (see q) [^T,q,Q]
*   U: very limited undo!! It only restores the LAST line killed!
    V: Unused
*  nW: Moves forward n words [w] {vix's concept of words not same}
=  nX: delete n characters before cursor
+  nY: append n lines to save buffer (see y), does not change buffer
=+ Zx: exit from vix (ZZ: normal, writes file, ZA: abort, no changes)
-  [[: Not implemented
    : Unused
-  ]]: Not implemented
=   ^: beginning of line {1st char of line, NOT 1st non-white char}
+   _: invoke indirect command file
=   a: append text starting after cursor
*   b: back up a word [see B]
=   c: change c, <sp>, ^, $, or / (delete, enter insert mode)
    =   c - change line
    =   <sp> - change one character
    =   ^ - to beginning of line
    =   $ - to end of line
    *   w - next word {VIX's concept of word different}
    -   b, and any others not mentioned not implemented
    +   / - the last thing found, yanked or put
=  nd: delete d, <sp>, ^, $, or /
    =   d - delete line
    =   <sp> - delete character
    =   ^ - to beginning of line
    =   $ - to end of line
    *   w - next word {VIX's concept of word different}
    -   b, and any others not mentioned not implemented
    +   / - the last thing found, yanked or put
-   e: Not implemented
-   f: Not implemented
    g: Unused
=  nh: Move left n characters [BS,^H] {will move over lines, too}
=  ni: insert (if value n supplied, then that ascii code inserted)
=  nj: down lines, in column [^J,^N]
=  nk: Up lines, in column [^K,^P]
=  nl: right n characters [<space>] {moves over lines, too}
*  nm: mark cur. line as location n.  Use M to return to location.
=   n: find next (in same direction as last ? or /)
=  no: open n following lines
=   p: put save buffer after cur line
+   q: Prefix character for "extended" commands
        b: goto real beginning of the file
        e: edit repeat buffer
        j: jump back to last location
        p: put external file from save buffer (writes file)
        r: restore repeat buffer
        s: print screen
        w: write buffer, read in next page of file being edited
       -n causes a buffer up to current line to be written
        y: yank external file to save buffer (reads file)
        /: cross buffer search (does automatic 'qw' on search)

     nq:p: set parameter 'p' to value 'n', parameters are:
         a: autoindent (1 means on, 0 off for all "switch" pars)
         c: "cut" mode (means 'dd' saves line in yank buffer, too)
         e: expand tabs to n spaces (8 default)
         d: home display line (where cursor homes after verify)
         f: find case mode (0 is case insensitive, 1 exact match)
         m: match wildcards (1 use ^A, ^L, etc., 0 no wild cards)
         o: requests new name for output file
         r: set current repeat buffer to n
         s: scroll window, cursor moves s lines before scrolling
         t: tty mode - 1: tty, 0: visual (you probably don' need this)
         u: requests entry of user wild card set
         v: virtual window size
         w: autowrap limit

=   r: replace next char with next character entered
=  ns: substitute: delete n characters, enter insert mode
-   t: Not implemented
-   u: Not implemented (see U)
    v: Unused
*  nw: advance word (see W)
=  nx: delete n characters
*  ny: yank text to save buffer - will save n lines into save buffer
       (Only one save buffer, 1st y clears buffer, rest add until
        non y command entered. dd works in a similar fashion, but
        kills as it saves (if cut_mode enabled)).
=   z: refresh screen (^L,^R)
-   {: Not implemented
-   |: Not implemented
=  n~: Change case of next n characters
* nDEL: Same as X, delete previous character

əəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəəə